
rst2texinfo
***********

:Author: Jon Waltman
:Contact: jonathan.waltman@gmail.com

``rst2texinfo`` is an extension of the Docutils text processing system
which adds support for generating Texinfo files from reStructuredText.


Introduction
============

The purpose of this program is to generate Info files from
reStructuredText documents.  Info is the underlying format of the
on-line help system used by the GNU Project.  This system provides a
useful and convenient method for reading manuals from the terminal or
within the Emacs text editor.  Although, the focus of this program is
to produce Info output, Texinfo can also be used to generate a variety
of different formats, including HTML, Latex, and plain text.  More
information on Texinfo can be found at
http://www.gnu.org/software/texinfo/.

rst2texinfo uses the following components:

* Python  (tested using v2.6) -- http://www.python.org/
* Docutils (tested using v0.6) -- http://docutils.sourceforge.net/

To create Info files, you will need the "makeinfo" program which is
part of the Texinfo project.


Install
=======

::

    python setup.py install


Invoking rst2texinfo
====================

::

    rst2texinfo.py [options] [<source> [<destination>]]

Reads reStructuredText from ``source`` and writes Texinfo to
``destination``.

.. rubric:: Texinfo Specific Options

In addition to the general options provided by Docutils, the following
options affect the output of rst2texinfo.

--texinfo-filename=<file>
   Specify the name of the Info file that would be created after
   running ``makeinfo`` on the generated Texinfo file.  Default
   behavior is to use the base name of the input source.

--texinfo-dir-entry=<name>
   Specify the name of the entry to create in the top level ``DIR``
   menu file.

   To create this entry, run ``install-info`` on the generated Info
   file.

--texinfo-dir-description=<desc>
   Descriptive text to appear in the top-level ``DIR`` menu file.

--texinfo-dir-category=<category>
   Specifies the section which this entry will appear in the top-level
   ``DIR`` menu file.


Converting Texinfo to Info
==========================

After converting your reStructuredText document to Texinfo, the next
step is to convert the Texinfo file to Info.  To do this, you will
need to use the ``makeinfo`` program.  Refer to the documentation for
more details but its general usage is::

    makeinfo --no-split FILENAME.texi

This should create a file named FILENAME.info which can then be read
using an "Info reader".


Reading Info Files
==================

There are two main programs for reading Info files, ``info`` and GNU
Emacs.  The ``info`` program has less features but is available on
most \*nix environments and can be quickly accessed at the terminal.
Emacs provides better font color displays and supports extensive
customization (of course).


Issues
======

The conversion of reST to Texinfo is not a seamless transition.  Info
is not as sophisticated as HTML which creates several issues since
most reST documents are geared for HTML output.  The following sections
describe some of these issues.


Displaying Links
----------------

One noticeable problem you may encounter with the generated Info files
is how references are displayed.  If you read the source of an Info
file, a reference to this section would look like::

    * note Displaying Links: target-id

In the stand-alone reader, ``info``, references are displayed just as
they appear in the source.  Emacs, on the other-hand, will by default
replace ``\*note:`` with ``see`` and hide the ``target-id``.  For
example:

    `Displaying Links`_

The exact behavior of how Emacs displays references is dependent on
the variable ``Info-hide-note-references``.  If set to the value of
``hide``, Emacs will hide both the ``\*note:`` part and the
``target-id``.  This is generally the best way to view reST documents
since they often make frequent use of links and do not take this
limitation into account.  However, changing this variable affects how
all Info documents are displayed and most due take this behavior into
account.

If you want Emacs to display Info files produced by rst2texinfo using the
value ``hide`` for ``Info-hide-note-references`` and the default value
for all other Info files, try adding the following Emacs Lisp code to
your start-up file, ``~/.emacs.d/init.el``.

::

    (defadvice info-insert-file-contents (after
                                          docutils-info-insert-file-contents
                                          activate)
      "Hack to make `Info-hide-note-references' buffer-local and
    automatically set to `hide' iff it can be determined that this file
    was created from a Texinfo file generated by Docutils or Sphinx."
      (set (make-local-variable 'Info-hide-note-references)
           (default-value 'Info-hide-note-references))
      (save-excursion
        (save-restriction
          (widen) (goto-char (point-min))
          (when (re-search-forward
                 "^Generated by \\(Sphinx\\|Docutils\\)"
                 (save-excursion (search-forward "" nil t)) t)
            (set (make-local-variable 'Info-hide-note-references)
                 'hide)))))


Notes
=====

The following notes may be helpful if you want to create Texinfo
files:

- Each section corresponds to a different ``node`` in the Info file.

- Some characters cannot be properly escaped in menu entries and
  xrefs.  The following characters are replaced by spaces in these
  contexts: ``@``, ``{``, ``}``, ``.``, ``,``, and ``:``.

- In the HTML and Tex output, the word ``see`` is automatically
  inserted before all xrefs.

- Links to external Info files can be created using the somewhat
  official URI scheme ``info``.  For example::

      info:Texinfo#makeinfo_options

  which produces:

      info:Texinfo#makeinfo_options

- Inline markup appears as follows in Info:

  * strong -- \*strong\*
  * emphasis -- _emphasis_
  * literal -- \`literal'


Copyright
=========

rst2texinfo and this documentation should have the same license as the
Docutils project.

Copyright © 2010  Jon Waltman. All rights reserved.
